DELETE /api/rooms/{roomID}

Clean up room resources including sandbox and conversation state

Destroys the sandbox environment and resets conversation state for a specific room. Use this endpoint when a conversation session ends or to free up resources.

Endpoint

DELETE /api/rooms/{roomID}

Path Parameters

roomID · string · required

Unique identifier for the room to clean up.

Response

Success (200 OK)

cleaned · boolean

Always true when cleanup completes.

roomId · string

The room ID that was cleaned up.

Partial Success (207 Multi-Status)

Returned when cleanup completes but some operations failed:

cleaned · boolean

Always true even when errors occur.

errors · string[]

Array of error messages from failed cleanup operations (e.g., sandbox destruction failures).

Example Request

curl -X DELETE https://your-worker.workers.dev/api/rooms/room-123

Example Response (Success)

{
  "cleaned": true,
  "roomId": "room-123"
}

Example Response (Partial Success)

{
  "cleaned": true,
  "errors": [
    "sandbox: Failed to destroy sandbox: connection timeout"
  ]
}

Cleanup Operations

The endpoint performs the following cleanup tasks:

1. Reset Agent State - Clears the conversation history (sets messages array to empty)
2. Destroy Sandbox - Terminates the sandbox-{roomID} instance and removes its resources

Implementation reference from cf-worker/index.ts:244-266:

private async handleCleanup(roomId: string): Promise<Response> {
  const errors: string[] = [];

  // Reset agent state
  this.setState({ messages: [] });

  // Terminate sandbox
  try {
    const sandbox = getSandbox(this.env.Sandbox, `sandbox-${roomId}`);
    await sandbox.destroy();
  } catch (e) {
    errors.push(`sandbox: ${e instanceof Error ? e.message : String(e)}`);
  }

  if (errors.length > 0) {
    return Response.json({ cleaned: true, errors }, { status: 207 });
  }

  return Response.json({ cleaned: true, roomId });
}

Error Handling

The cleanup endpoint is designed to be resilient:

• Best-effort cleanup: Even if sandbox destruction fails, the agent state is still reset
• Partial success reporting: Returns 207 status with error details rather than failing completely
• No rollback: Successful cleanup operations are not reversed if later operations fail

Error Responses

404 Not Found

Returned when the room ID is missing from the URL path.

405 Method Not Allowed

Returned when using a method other than DELETE.

Use Cases

• End of conversation session cleanup
• Resource management and memory optimization
• Resetting a room to initial state
• Automated cleanup in test environments

Client Implementation Example

From internal/ai/client.go:106-125:

func (c *Client) CleanupRoom(ctx context.Context, roomID string) error {
    url := fmt.Sprintf("%s/api/rooms/%s", c.baseURL, roomID)

    req, err := http.NewRequestWithContext(ctx, http.MethodDelete, url, nil)
    if err != nil {
        return fmt.Errorf("create cleanup request: %w", err)
    }

    resp, err := c.http.Do(req)
    if err != nil {
        return fmt.Errorf("cleanup request failed: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode >= 400 {
        return fmt.Errorf("cleanup failed with status %d", resp.StatusCode)
    }

    return nil
}

Related Endpoints

• POST /api/rooms//message - Send messages to the AI assistant
• POST /api/rooms//sandbox/exec - Execute sandbox commands